home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 051-075 / disk_065 / newpackets / packets.doc
Text File  |  1992-05-06  |  11KB  |  269 lines
  1. ==========================
  2. amiga.dev/docs #4, from cscheppner, 11077 chars, Tue Feb 24 18:21:20 1987
  3. --------------------------
  4.               NEW PACKETS AND STRUCTURES IN 1.2 AMIGADOS
  5.               ==========================================
  6.                          Carolyn Scheppner
  7.  
  8.       AmigaDOS contains many features which can only be accessed
  9.    by sending a packet directly to a process.  One example is the
  10.    ACTION_INHIBIT packet which can be sent to the handler process
  11.    of a disk drive to stop the verification which normally occurs
  12.    when disks are inserted.  This packet is used by Diskcopy and
  13.    Format to prevent disk verification and "Not a DOS Disk"
  14.    requestors during the format or backup process.  The packet is
  15.    sent to the MsgPort of a drive's handler.
  16.  
  17.       The handler MsgPort of most named AmigaDOS devices (like DF0:)
  18.    can be found with the DeviceProc() function.  Note that DeviceProc()
  19.    can not be used to find a CON: or RAW: handler because there may be
  20.    many handlers for each of these.  The handler MsgPort (ProcessID)
  21.    of a CON: or RAW: window is in its FileHandle structure (fh_Type).
  22.    The MsgPort of a CLI process's "*" window is process->pr_ConsoleTask.
  23.  
  24.    Examples:
  25.  
  26.    1. port = (struct MsgPort *)DeviceProc("DF1:");
  27.  
  28.    2. fh = Open("CON:0/40/640/140/Test",MODE_NEWFILE);
  29.       port = (struct MsgPort *)(((struct FileHandle *)(fh<<2))->fh_Type);
  30.  
  31.    3. myCliProc = (struct Process *)FindTask(NULL);
  32.       port = myCliProc->pr_ConsoleTask;
  33.  
  34.  
  35.       A struct StandardPacket contains an exec Message structure
  36.    and an AmigaDOS DosPacket structure.
  37.  
  38.       struct StandardPacket {
  39.          struct Message    sp_Msg;
  40.          struct DosPacket  sp_Pkt;
  41.          };
  42.  
  43.       This combined structure is only used for convenience since
  44.    the DosPacket structure does not have to directly follow the
  45.    Message structure in memory.
  46.  
  47.       The actual linkage between the Message and the Packet are
  48.    pointers in each structure which point to each other.  The
  49.    Message's mn_Node.ln_Name member must be initialized to point
  50.    to the DosPacket, and the Packet's dp_Link field must point
  51.    to the exec Message.
  52.  
  53.       packet->sp_Msg.mn_Node.ln_Name = (char *)&(packet->sp_Pkt);
  54.       packet->sp_Pkt.dp_Link         = &(packet->sp_Msg);
  55.  
  56.       StandardPacket or DosPacket structures must be longword aligned
  57.    and should be dynamically allocated in any language where such
  58.    alignment can not be specified for variables.  The same is true
  59.    for any structures you are asking DOS to fill, such as the InfoData
  60.    structure initialized via the ACTION_DISK_INFO packet.
  61.  
  62.       struct DosPacket {
  63.          struct Message  *dp_Link;   /* Link to the Exec Message  */
  64.          struct MsgPort  *dp_Port;   /* Reply port for the packet */
  65.          LONG  dp_Type;              /* Packet action number/type */
  66.          LONG  dp_Res1;              /* Return value 1            */
  67.          LONG  dp_Res2;              /* Return value 2            */
  68.          LONG  dp_Arg1;              /* Packet arguments          */
  69.            through
  70.          LONG  dp_Arg7;
  71.          };
  72.  
  73.  
  74.       The Technical Reference portion of the AmigaDOS manual details
  75.    the arguments and usage of most packet types.  There are several
  76.    new packet types in 1.2 AmigaDOS, and an enhancement to the
  77.    existing DiskInfo packet.  Note that the new packet numbers are
  78.    not defined in the libraries/dosextens headers.  You can define
  79.    these new packet numbers in your own code.
  80.  
  81.  
  82.          DESCRIPTIONS OF NEW AND ENHANCED DOS PACKET TYPES
  83.          =================================================
  84.  
  85.       If your program uses new 1.2 functions or features such as the
  86.    new packets, your code should make sure that it is being run on
  87.    a system booted with at least v1.2.  To do this, specify version
  88.    number 33 in your OpenLibrary() calls and abort gracefully if
  89.    the OpenLibrary() returns NULL.
  90.  
  91.       The Res1 result of most of these packets is BOOLEAN (0L = failure).
  92.    But DiskInfo is documented as always returning TRUE (-1L) and it
  93.    appears that SetRawCon does the same.  
  94.  
  95.    1) SetFileDate ( ACTION_SET_DATE = 34L )
  96.       Sets the date of a file or directory to specified date.
  97.       The packet is sent to the MsgPort returned by DeviceProc(filename).
  98.       The args for the packet are
  99.          arg[0] = NULL
  100.          arg[1] = lock on ParentDir of file
  101.          arg[2] = BPTR to BSTR of filename
  102.          arg[3] = APTR to a DateStamp structure
  103.  
  104.       A new CLI command SetDate <file> <date> [<time>] is also provided.
  105.       Note that SetFileDate packet and SetDate command did not work
  106.       properly on both ram and disk files until Release version of 1.2.
  107.  
  108.    2) SetRawMode ( ACTION_SCREEN_MODE = 994L )
  109.       Switches CON: into raw mode and back again. The single argument
  110.       is DOS TRUE (-1L) for raw mode (as if RAW: had been requested)
  111.       and DOS FALSE (0L) to turn it back to CON: style.  The packet is
  112.       sent to a (struct MsgPort *)process->pr_ConsoleTask.
  113.  
  114.       Note that in addition to this, an escape sequence may be sent
  115.       to turn on or off the automatic translation of LF to CR/LF.
  116.       Normally RAW: does not enable this and CON: does.  SetRawMode
  117.       does not affect the translation.  The escape sequences are
  118.       CSI 20h to enable, and CSI 20l to disable this translation.
  119.  
  120.    3) Flush ( ACTION_FLUSH = 27L )
  121.       Cause pending blocks to be written out and motor turned off.
  122.       This is expensive, so should not be done after every write.
  123.       It is used by the system before putting up a requestor saying
  124.       "Change Disk" and the packet is only returned when the job
  125.       is done.  This action would be useful in a database when it
  126.       wished to commit.
  127.  
  128.    4) MoreCache ( ACTION_MORE_CACHE = 18L )
  129.       The single argument indicates the number of extra cache buffers
  130.       to be obtained for use.  Used by ADDBUFFERS command.
  131.  
  132.    5) DiskInfo ( ACTION_DISK_INFO = 25L )
  133.       When sent to a console handler, this packet now returns not only
  134.       the window pointer in the id_VolumeNode field, but also a pointer
  135.       to the console handler's console IO block in the id_InUse field.
  136.       (These fields are part of the InfoData structure initialized by
  137.       ACTION_DISK_INFO).  Remember that you must AllocMem your InfoData
  138.       structure to assure longword alignment since a BPTR to this
  139.       structure is arg[0] for the packet.
  140.  
  141.       A pointer to the ConUnit structure (see devices/conunit.h, .i)
  142.       can be found from the returned console IO block pointer:
  143.  
  144.          conUnit = (struct ConUnit *)
  145.                       ((struct IOStdReq *)infoData->id_InUse)->io_Unit;
  146.  
  147.       There is a lot of useful information in the ConUnit structure
  148.       such as text cursor position and limits.  If you are using the
  149.       exec console.device directly, you should be able to get the
  150.       ConUnit pointer from yourIoRequest->io_Unit.
  151.  
  152.  
  153.                    EXAMPLE PACKET SENDING FUNCTION
  154.                    ===============================
  155.  
  156. #include <exec/types.h>
  157. #include <exec/memory.h>
  158. #include <libraries/dos.h>
  159. #include <libraries/dosextens.h>
  160. ...
  161. /*
  162.  * sendpkt() by A. Finkel, P. Lindsay, C. Scheppner
  163.  *  returns Res1 of the reply packet
  164.  */
  165.  
  166. LONG sendpkt(pid,action,args,nargs)
  167. struct MsgPort *pid;  /* process indentifier (handler message port) */
  168. LONG action,          /* packet type (desired action) */
  169.      args[],          /* a pointer to a argument list */
  170.      nargs;           /* number of arguments in list  */
  171.    {
  172.    struct MsgPort        *replyport;
  173.    struct StandardPacket *packet;
  174.  
  175.    LONG  count, *pargs, res1;
  176.  
  177.    replyport = (struct MsgPort *) CreatePort(NULL,0);
  178.    if(!replyport) return(NULL);
  179.  
  180.    packet = (struct StandardPacket *)
  181.       AllocMem((long)sizeof(struct StandardPacket),MEMF_PUBLIC|MEMF_CLEAR);
  182.    if(!packet)
  183.       {
  184.       DeletePort(replyport);
  185.       return(NULL);
  186.       }
  187.  
  188.    packet->sp_Msg.mn_Node.ln_Name = (char *)&(packet->sp_Pkt);
  189.    packet->sp_Pkt.dp_Link         = &(packet->sp_Msg);
  190.    packet->sp_Pkt.dp_Port         = replyport;
  191.    packet->sp_Pkt.dp_Type         = action;
  192.  
  193.    /* copy the args into the packet */
  194.    pargs = &(packet->sp_Pkt.dp_Arg1);   /* address of first argument */
  195.    for(count=0;count < nargs;count++)
  196.       pargs[count]=args[count];
  197.  
  198.    PutMsg(pid,packet); /* send packet */
  199.  
  200.    WaitPort(replyport);
  201.    GetMsg(replyport);
  202.  
  203.    res1 = packet->sp_Pkt.dp_Res1;
  204.  
  205.    FreeMem(packet,(long)sizeof(struct StandardPacket));
  206.    DeletePort(replyport);
  207.  
  208.    return(res1);
  209.    }
  210.  
  211.  
  212.                     AMIGADOS 1.2 STRUCTURE CHANGES
  213.                     ==============================
  214.  
  215.    PATH LIST:
  216.       The path list is held as a BPTR in the CommandDir member of the
  217.       CommandLineInterface structure.  Although currently documented
  218.       as the lock on the command directory, this is either 0 or a
  219.       BPTR to a list of path elements, each consisting of:
  220.          BPTR NextPath     (BPTR to next list entry)
  221.          BPTR PathLock     (a lock on the directory)
  222.  
  223.    RESIDENT SEGMENT LIST:
  224.       The resident segment list is held as a BPTR in the DosInfo
  225.       substructure within the global data structure.  The segment
  226.       list replaces the slot currently defined as NetHand, and is
  227.       byte offset 16 from the DosInfo base.  Each entry is:
  228.          BPTR  NextEntry    (BPTR to next list entry)
  229.          LONG  UseCount     (Use count for segment, -1 if unloadable)
  230.          BPTR  SegPtr       (Segment pointer)
  231.          BSTR  SegName      (Segment Name)
  232.  
  233.    DEVINFO STRUCTURE:
  234.       The specification of the DevInfo structure has been expanded.
  235.       The GlobVec member used when the DevInfo refers to a device
  236.       (Type = DLT_DEVICE = 0) is documented as being a global
  237.       vector pointer or 0.  Now this value may be -1 indicating
  238.       that the handler process does not need a global vector and
  239.       should be called as a C process.
  240.  
  241.       The DevInfo structure is described in the AmigaDOS Technical
  242.       reference manual, but does not appear in the dosextens headers.
  243.       It is basically the same as the DeviceList structure described
  244.       in dosextens, with device-specific redefinitions of the fifth
  245.       through tenth longwords in the structure.
  246.  
  247.       struct DevInfo
  248.          {
  249.          BPTR  Next;       /* Next list entry or 0 */
  250.          LONG  Type;       /* Entry Type (0=device,1=dir,2=vol ?) */
  251.          APTR  Task;       /* Handler process msgport or 0 */
  252.          BPTR  Lock;       /* File system lock or 0 */
  253.          BSTR  Handler;    /* File name of handler or 0 */
  254.          LONG  Stacksize;  /* Stack size for handler process */
  255.          LONG  Priority;   /* Priority for handler process */
  256.          LONG  Startup;    /* Startup value passed to handler */
  257.          BPTR  SegList;    /* SegList for handler process or 0 */
  258.          BPTR  GlobVec;    /* Global vector, or 0, or - 1 */
  259.          BSTR  Name;       /* Name of device or ASSIGN'd name */
  260.          };
  261.  
  262.       The AmigaDOS device list can be found from DosBase.
  263.          dl =  (struct DosLibrary *)DosBase;
  264.          rn =  (struct RootNode *)dl->dl_Root;
  265.          di =  (struct DosInfo *)BADDR(rn->rn_Info);
  266.          dev = (struct DevInfo *)BADDR(di->di_DevInfo);
  267.  
  268.  
  269.